/**
 * Copyright (C) 2012 Foxit Corporation.
 * All Rights Reserved.
 *
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation.<br> 
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit.<br>
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement.<br>
 * Without SDK license agreement, you cannot redistribute anything.
 * 
 * @file	fpdfannot.h
 * @brief	Header file for the PDF Annotation object module.
 * @details	The annot module offers methods to do some operations on annotations.<br>
 *			Following the specification of PDF, users can retrieve a annotation in the current position<br>
 *			as well as add, delete or modify annotations by using these methods.<br>
 *			This module currently supports annotations of these types: fileattachment, stamp, pencil, highlight, note, link,<br>
 *			square, circle, line, underline, strikeout, squiggly, freetext and screen annotation.
 *
 * @note	If you want to purchase Foxit PDF SDK license and use ANY of the following functions, please
 *			request for enabling PDF object module explicitly. 
 */
 
 /** 
 * @addtogroup FGSPDFAnnot PDF Annotation 
 * @brief Methods in this module are included in fpdfannot.h
 */
 
 /** @{*/


#ifndef __FGSPDFANNOT__
#define __FGSPDFANNOT__

#include "fpdfbase.h"

#ifdef __cplusplus
extern "C" {
#endif

/************************************************************************/
/*								Annotation                              */
/************************************************************************/
/**
 * @brief	Get the count of hyperlinks inside a page.
 *
 * @param[in] page			Reference to a PDF page.
 *
 * @return	The count of links.
 *
 * @note At present, support the following types of annotations: fileattachment, stamp, pencil, highlight, note,<br>
 *		 square, circle, line, underline, strikeout, squiggly, freetext, and screen annotation.
 */
SInt32 FGSPDFAnnotGetAnnotCount(FGSPDFPageRef page);

/**
 * @brief	Get the handler of the annotation by the index.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] annot_index	The zero-based annotation index.
 *
 * @return	The annotation reference.
 */
FGSPDFAnnotRef FGSPDFAnnotGetAnnotByIndex(FGSPDFPageRef page, SInt32 annot_index);

/**
 * @brief	Get the index of the annotation by the annotation reference.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] annot			Reference to a PDF annotation.
 *
 * @return	 the zero-based annotation index.
 */
SInt32 FGSPDFAnnotGetAnnotIndex(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/**
 * @brief	Get the reference of the annotation which is the nearest one to a certain position on the page.
 *
 * @details	When the point is inside an annotation, this annotation is the nearest one to the point.
 *			Otherwise this annotation cannot be the nearest one to the point.<br>
 *			If there is no nearest annotation, the return value will be -1.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] pt			The value of position in the PDF page coordination system.
 *
 * @return	The pointer to the annotation reference.
 */
FGSPDFAnnotRef FGSPDFAnnotGetAnnotAtPos(FGSPDFPageRef page, CGPoint pt);

/** 
 * @brief	Get type of an annotation.
 * @param[in] page          Reference to a PDF page.
 * @param[in] annot         Reference to a PDF annotation.
 *
 * @return The type of the annotation.
 */
FGSPDFAnnotType FGSPDFAnnotGetAnnotType(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/** 
 * @brief	Get the rect of an annotation.
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 *
 * @return The rect of the annotation.
 */
CGRect FGSPDFAnnotGetAnnotRect(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/** 
 * @brief	Get the border color of an annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 *
 * @return The color of the annotation border.
 */
UInt32 FGSPDFAnnotGetAnnotBorderColor(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/** 
 * @brief To get the color filled in the rect of an annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 *
 * @return The color filled in the annotation rect.
 */
UInt32 FGSPDFAnnotGetAnnotFillColor(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/** 
 * @brief To get the intent of the annotation 
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 *
 * @return The intent of the annotation, user should release the string by calling <b>CFRelease</b>.
 */
CFStringRef FGSPDFAnnotCopyAnnotIntent(FGSPDFPageRef page, FGSPDFAnnotRef annot); 

/** 
 * @brief To get the author of the annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 *
 * @return The author of the annotation, user should release the string by calling <b>CFRelease</b>.
 */
CFStringRef	FGSPDFAnnotCopyAnnotAuthor(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/** 
 * @brief To get the subject of the annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 *
 * @return The subject of the annotation, user should release the string by calling <b>CFRelease</b>.
 */
CFStringRef	FGSPDFAnnotCopyAnnotSubject(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/** 
 * @brief To get the content of the annotation
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 *
 * @return The content string of the annotation, user should release the string by calling <b>CFRelease</b>.
 */
CFStringRef FGSPDFAnnotCopyAnnotContents(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/** 
 * @brief To get the opacity of the annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 *
 * @return A float number to show the opacity of the annote.
 */
UInt32 FGSPDFAnnotGetAnnotOpacity(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/** 
 * @brief To get the width of border of annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 *
 * @return The width of border.
 */
SInt32 FGSPDFAnnotGetAnnotBorderWidth(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/** 
 * @brief To get the width of border of annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 * @param[out] date		Pointer to the <b>::CFGregorianDate</b> that receives the modified date.
 *
 * @return ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotGetAnnotModifiedDate(FGSPDFPageRef page, FGSPDFAnnotRef annot, CFGregorianDate *date);

/** 
 * @brief To get the action of annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 *
 * @return The action reference of annotation.
 */
FGSPDFActionRef	FGSPDFAnnotGetAction(FGSPDFPageRef page, FGSPDFAnnotRef annot);
    
/** 
 * @brief	Insert the specified annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annotType	The action type of annotation.
 * @param[in] index		The index of annotatation, if index is out of range, annot will be inserted to the end.
 *
 * @return The Reference to a PDF annotation.
 */
FGSPDFAnnotRef 	FGSPDFAnnotInsertAnnot(FGSPDFPageRef page, FGSPDFAnnotType annotType, SInt32 index);
    
/** 
 * @brief	Delete annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 *
 * @return ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotDeleteAnnot(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/** 
 * @brief	Get the rectangle of the annotation.
 *
 * @param[in] page				Reference to a PDF page.
 * @param[in] annot				Reference to a PDF annotation.
 * @param[out] newRect			Pointer to the rectangle of the annotation after adding the matrix.
 * @param[in] resetAppearance	Reset the appearance if TRUE, else not.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotSetAnnotRect(FGSPDFPageRef page, FGSPDFAnnotRef annot, CGRect *newRect, Boolean resetAppearance);

/** 
 * @brief	Get border color of the annotation.
 *
 * @param[in] page              Reference to a PDF page.
 * @param[in] annot             Reference to a PDF annotation.
 * @param[out] color            The color of the border.
 * @param[in] resetAppearance	Reset the appearance if TRUE, else not.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotSetAnnotBorderColor(FGSPDFPageRef page, FGSPDFAnnotRef annot, UInt32 color, Boolean resetAppearance);

/** 
 * @brief	Get color filling the rectangle of the annotation.
 *
 * @param[in] page                  Reference to a PDF page.
 * @param[in] annot                 Reference to a PDF annotation.
 * @param[in] color                 The color filling the rectangle.
 * @param[in] resetAppearance		Reset the appearance if TRUE, else not.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotSetAnnotFillColor(FGSPDFPageRef page, FGSPDFAnnotRef annot, UInt32 color, Boolean resetAppearance);

/** 
 * @brief	Set the intent of an annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 * @param[in] intent	The intent to set to the annotation.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotSetAnnotIntent(FGSPDFPageRef page, FGSPDFAnnotRef annot, CFStringRef intent); 

/** 
 * @brief	Set author to an annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 * @param[in] author	The author to set to the annotation.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotSetAnnotAuthor(FGSPDFPageRef page, FGSPDFAnnotRef annot, CFStringRef author);

/** 
 * @brief	Set subject to an annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 * @param[in] subject	The subject to set to the annotation.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotSetAnnotSubject(FGSPDFPageRef page, FGSPDFAnnotRef annot, CFStringRef subject);

/** 
 * @brief	Set the content of an annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 * @param[in] content	The content to set to the annotation.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotSetAnnotContents(FGSPDFPageRef page, FGSPDFAnnotRef annot, CFStringRef contents);

/** 
 * @brief	Set the opacity of an annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 * @param[in] opacity	The opacity to set to the annotation.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotSetAnnotOpacity(FGSPDFPageRef page, FGSPDFAnnotRef annot, UInt32 opacity);

/** 
 * @brief	Set the width of an annotation border.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 * @param[in] width 	The width to set to the annotation border.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotSetAnnotBorderWidth(FGSPDFPageRef page, FGSPDFAnnotRef annot, Float32 width);

/** 
 * @brief	Set the data of an annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 * @param[in] date	 	Pointer to the date to set to the annotation border.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotSetAnnotModifiedDate(FGSPDFPageRef page, FGSPDFAnnotRef annot, CFGregorianDate *date);

/** 
 * @brief	Set the action of an annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 * @param[in] action	Reference to the action to set to the annotation border.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet	FGSPDFAnnotSetAnnotAction(FGSPDFPageRef page, FGSPDFAnnotRef annot, FGSPDFActionRef action);

/** 
 * @brief Start rendering an annotation.
 *
 * @param[in] bitmapContext	Reference to context which use to render the annotation.
 * @param[in] page			Reference to a PDF page.
 * @param[in] matrix		Pointer to the matrix to add to the annotation.
 * @param[in] flags			0 for normal display, or combination of flags FDP_LCD_TEXT and FDP_BGR_STRIPE
 * @param[in] clip			Pointer to the clip rectangle (in bitmap device coordinations),<br>
 *							or null if no clipping needed.
 * @param[in] pause			Pointer to the pause of the rendering process.<br>
 * 							Can be null if no pausing is needed.
 * @param[in] renderer		Pointer to receiving renderer reference.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotStartRenderingAnnots(CGContextRef bitmapContext, FGSPDFPageRef page, CGAffineTransform *matrix, SInt32 flags, CGRect *clip, FGSPause *pause, FGSDPRenderRef *renderer);

/** 
 * @brief Continue rendering the annotation after some pause point.
 *
 * @param[in] renderer	Reference to the render use to render the annotation.	
 * @param[in] pause		Pointer to the pause point of rendering to be continued.
 *
 * @return	::kFGSErrorSuccess means successfully.<br> 
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotContinueRenderingAnnots(FGSDPRenderRef renderer,  FGSPause *pause);

/** 
 * @brief Stop rendering the annotation.
 *
 * @param[in] renderer	Reference to renderer used to render the annotation.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotStopRenderingAnnots(FGSDPRenderRef renderer);

//*****************************************************************************
//* Popup annotation method
//*****************************************************************************

/**
 * @brief	Get popup annotation.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] annot			Reference to a PDF annotation.	
 *
 * @return  The popup annotation.
 * 
 */
FGSPDFAnnotRef FGSPDFAnnotGetAnnotPopup(FGSPDFPageRef page, FGSPDFAnnotRef annot);
    
/**
 * @brief	Judgment annotation popup is open or not.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] annot			Reference to a PDF annotation.	
 *
 * @return	    True means popup is open.
 * 
 */
Boolean	FGSPDFAnnotGetPopupOpen(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/**
 * @brief	Set annotation popup is open.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] annot			Reference to a PDF annotation.	
 * @param[in] bOpen			True means popup is open.	
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * 
 */
FGSErrorRet	FGSPDFAnnotSetPopupOpen(FGSPDFPageRef page, FGSPDFAnnotRef annot, Boolean bOpen);

/**
 * @brief	Get popup annotation's parent annotation.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] annot			Reference to a PDF annotation.	
 *
 * @return	    The parent annotation of specified popup annotation.
 * 
 */
FGSPDFAnnotRef FGSPDFAnnotGetPopupParent(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/** 
 * @brief	Get the link area count in the annotation.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] link_annot	Reference to a PDF annotation.
 *
 * @return The number of the link area in the annotation.
 */
SInt32 FGSPDFAnnotGetLinkAreaCount(FGSPDFPageRef page, FGSPDFAnnotRef link_annot);

/************************************************************************/
/*								Link                                    */
/************************************************************************/
/** 
 * @brief	Get the link area in the annotation.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] link_annot	Reference to a PDF annotation of the link note to get area.
 * @param[in] area_index	The index of the link area.
 * @param[out] points		Points to describe the link area.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotGetLinkArea(FGSPDFPageRef page, FGSPDFAnnotRef link_annot, SInt32 area_index, CGPoint points[4]);

/** 
 * @brief	Set the link area in the annotation.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] link_annot	Reference to a PDF annotation of the link note to get area.
 * @param[in] area_index	The index of the link area.
 * @param[in] points		Points to describe the link area.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotSetLinkArea(FGSPDFPageRef page, FGSPDFAnnotRef link_annot, SInt32 area_index, CGPoint points[4]);
    
/*****************************************************************************/
/*									Note                                     */
/*****************************************************************************/
/**
 * @brief	Get annotation note icon type information.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	
 *
 * @return	    The annotation note icon type information.
 * 
 * @note Only support kFGSPDFNoteIconCheckMark now.
 */
FGSPDFNoteIconType FGSPDFAnnotGetNoteIconType(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/**
 * @brief	Set annotation note icon type information.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	
 * @param[in] type		The annotation note icon type information.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * 
 * @note Only support kFGSPDFNoteIconCheckMark now.
 */
FGSErrorRet FGSPDFAnnotSetNoteIconType(FGSPDFPageRef page, FGSPDFAnnotRef annot, FGSPDFNoteIconType type);

/************************************************************************/
/*								Ink									    */
/************************************************************************/
/**
 * @brief	Count the annotation ink paths.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	
 *
 * @return	The annotation ink paths count.
 * 
 */
SInt32 FGSPDFAnnotCountInkPaths(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/**
 * @brief	Get the annotation ink paths count information.
 *
 * @param[in] page          Reference to a PDF page.
 * @param[in] annot         Reference to a PDF annotation.	
 * @param[in] index         The index of the annotation ink paths.
 * @param[out] points       Points to CGPoint objects to receives the link path.
 * @param[out] count        Pointer to SInt32 object to receives the count number of points.
 * 
 * @return	The annotation ink paths count information.
 * 
 */
FGSErrorRet FGSPDFAnnotGetInkPath(FGSPDFPageRef page, FGSPDFAnnotRef annot, SInt32 index, CGPoint points[], SInt32 *count);
/**
 * @brief	Delete the annotation ink paths.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	
 * @param[in] index     The index of the annotation ink paths.
 * 
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFAnnotDeleteInkPaths(FGSPDFPageRef page, FGSPDFAnnotRef annot, SInt32 index);
	
/**
 * @brief	Add the annotation ink paths information.
 *
 * @param[in] page          Reference to a PDF page.
 * @param[in] annot         Reference to a PDF annotation.	
 * @param[out] points       The annotation ink paths information to be added.
 * @param[out] count        The count number of points.
 * 
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * 
 */
FGSErrorRet	FGSPDFAnnotAddInkPaths(FGSPDFPageRef page, FGSPDFAnnotRef annot, CGPoint points[], SInt32 count);
	
/************************************************************************/
/*								Stamp                                   */
/************************************************************************/
/**
 * @brief	Set annotation stamp image information.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] annot			Reference to a PDF annotation.	
 * @param[in] imagePath		The path of the stamp image.	
 * @param[in] imageType		The type of the stamp image
 * 
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * 
 */
FGSErrorRet	FGSPDFAnnotSetStampImage(FGSPDFPageRef page, FGSPDFAnnotRef annot, CFStringRef imagePath, SInt32 imageType);
	
/************************************************************************/
/*								FileAttachment                          */
/************************************************************************/

/**
 * @brief	Get annotation file attachment fileSpec information.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] annot			Reference to a PDF annotation.			
 *
 * @return	The annotation fileSpec information.
 * 
 */
FGSPDFFileSpecRef FGSPDFAnnotGetFileAttachmentFileSpec(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/**
 * @brief	Set annotation file attachment fileSpec information.
 *
 * @param[in] page			Reference to a PDF page.
 * @param[in] annot			Reference to a PDF annotation.	
 * @param[in] fileSpec		Reference to a PDF fileSpec information.	
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * 
 */
FGSErrorRet	FGSPDFAnnotSetFileAttachmentFileSpec(FGSPDFPageRef page, FGSPDFAnnotRef annot, FGSPDFFileSpecRef fileSpec);
    
/************************************************************************/
/*								Line                                    */
/************************************************************************/

/**
 * @brief	Get annotation line information.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	
 * @param[out] start	Pointer to CGPoint object to receives the start point of the line.	
 * @param[out] end		Pointer to CGPoint object to receives the end point of the line.	
 * 
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * 
 */	
FGSErrorRet FGSPDFAnnotGetLinePoints(FGSPDFPageRef page, FGSPDFAnnotRef annot, CGPoint *start, CGPoint *end);
    
/**
 * @brief	Set annotation line information.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	
 * @param[in] start		The start point of the line.	
 * @param[in] end		The end point of the line.	
 * 
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * 
 */
FGSErrorRet FGSPDFAnnotSetLinePoints(FGSPDFPageRef page, FGSPDFAnnotRef annot, CGPoint start, CGPoint end);
    
/************************************************************************/
/*								FreeText                                */
/************************************************************************/

/**
 * @brief	Get the annotation free text font name.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	
 *
 * @return	The font name of the annotation free text, user should release the string by calling <b>CFRelease</b>.
 * 
 */	
CFStringRef	FGSPDFAnnotCopyFreeTextFontName(FGSPDFPageRef page, FGSPDFAnnotRef annot);
    
/**
 * @brief	Get the annotation free text font size.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	 
 *
 * @return	  The font size of the annotation free text.	  
 * 
 */    
Float32	FGSPDFAnnotGetFreeTextFontSize(FGSPDFPageRef page, FGSPDFAnnotRef annot);

/**
 * @brief	Get the annotation free text font color.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.		
 *
 * @return	The color of the annotation free text.
 * 
 */	    
UInt32 FGSPDFAnnotGetFreeTextColor(FGSPDFPageRef page, FGSPDFAnnotRef annot);
    
/**
 * @brief	Set the annotation free text font name.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	
 * @param[in] fontName	The font name of the annotation free text.	
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * 
 */    
FGSErrorRet FGSPDFAnnotSetFreeTextFontName(FGSPDFPageRef page, FGSPDFAnnotRef annot, CFStringRef fontName);

/**
 * @brief	Set the annotation free text font size.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	
 * @param[in] fontSize	The font size of the annotation free text.	
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * 
 */	    
FGSErrorRet FGSPDFAnnotSetFreeTextFontSize(FGSPDFPageRef page, FGSPDFAnnotRef annot, Float32 fontSize);
    
/**
 * @brief	Set the annotation free text font color.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	
 * @param[in] color		The color of the annotation free text.	
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * 
 * @note Set alpha value, see <b>::FGSPDFAnnotSetAnnotOpacity</b>.
 *
 */	    
FGSErrorRet FGSPDFAnnotSetFreeTextColor(FGSPDFPageRef page, FGSPDFAnnotRef annot, UInt32 color);
    
/************************************************************************/
/*	Highlight, Underline, Squiggly, StrikeOut                           */
/************************************************************************/
/**
 * @brief	Get annotation comment quad points.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	
 * @param[out] points	The annotation comment quad points. 
 * @param[out] count	Pointer to SInt32 to receives the count number of annotation quad points. 
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * 
 */    
FGSErrorRet	FGSPDFAnnotGetCommentQuadPoints(FGSPDFPageRef page, FGSPDFAnnotRef annot, CGPoint points[], SInt32 *count);

/**
 * @brief	Set annotation comment quad points.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	
 * @param[in] points	The annotation comment quad points.	
 * @param[out] count	The count number of annotation quad points, and should be 4*i(i = 1, 2, ...).
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * 
 */   
FGSErrorRet FGSPDFAnnotSetCommentQuadPoints(FGSPDFPageRef page, FGSPDFAnnotRef annot, CGPoint points[], SInt32 count);
    
/** 
 * @brief Regenerate the appearance of an annotation.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.
 *
 * @return ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 * @note When the info of the annotation which contributes to its appearance is changed,<br>
 *		 the appearance of the annotation is also required to be regenerated.
 *
 */
FGSErrorRet FGSPDFAnnotResetAppearance(FGSPDFPageRef page, FGSPDFAnnotRef annot);
    
/**
 * @brief	Set annot border style.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.	
 * @param[in] style		The annot border style.	
 * 						For more definitions please see macro definitions <b>::FGSPDFAnnotBorderType</b>.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * 
 */
FGSErrorRet FGSPDFAnnotSetBorderStyle(FGSPDFPageRef page, FGSPDFAnnotRef annot, FGSPDFAnnotBorderType style);

/**
 * @brief	Get annot border style.
 *
 * @param[in] page		Reference to a PDF page.
 * @param[in] annot		Reference to a PDF annotation.		
 *
 * @return	    The annot border type.
 * 
 */
FGSPDFAnnotBorderType FGSPDFAnnotGetBorderStyle(FGSPDFPageRef page, FGSPDFAnnotRef annot);

#ifdef __cplusplus
};
#endif

#endif // _FPDFANNOT_
/**@}*/

